R Markdown Documents

Modern Computer Output

Introduction to R Markdown

Markdown documents provide the modern way of creating output for data analysis. The output is your finished report that includes not only the computer analysis, but your writing such as interpretation of that analysis. Instead of manually copying and pasting text and graphical output from R and other data analytic languages into a word processing document, R Markdown generates the document for you.

The purpose of a markdown document is to run a process that transforms the document into formatted output, such as a Word document with headers and other formatting that includes embedded computer output. R Markdown documents contain simple formatting codes. For example, a line of your writing that begins with a #, when transformed into a report, displays in the report as a first-level header. Begin a line with ## for a second-level header, etc. A word or phrase enclosed in a single * on each side displays in italics. In addition to your own writing, blocks of embedded code, such as R code, generate output embedded in the report.

Set up and run R Markdown files, filetype .Rmd, to create dynamic web (HTML), MS Word, or pdf output files. The output of a markup document blends text with code from R, or other languages such as Python, to dynamically create statistical output with your interpretative text.

Create an R Markdown Document

Although R Markdown exists apart from RStudio, here, as usual, we do our development within RStudio. Begin to create an R Markdown document by opening RStudio. In this example, there are no .R or .Rmd files present when RStudio is opened, so just the R console opens on the left side of the RStudio window.

Open RStudio with no input files present.

Within RStudio, go to the File menu and select New File, then R Markdown… . Or, as illustrated in the following figure, click on the + sign at the top-left corner of the RStudio window and select R Markdown… .

Create an R Markdown file.

The following dialogue appears. Enter the title of the document and choose the form of output. HTML (web page) is default. As indicated in the dialogue box, even if your ultimate goal is to produce a Word document, start with HTML. That way you do not need to be bothered with paging issues as the report is written to a single web page. Later you can easily convert to generate Word output.

Title and type of document.

Title the document.

Enter the title.

RStudio provides an example document when you create a new markdown document. The sample document is just about self-explanatory. A markdown document consists of code blocks, R code in this example, and explanatory text. When processed, the markdown documents formats the text and runs the code, displaying the output by default. Some details follow, illustrated with this sample document.

R Code Blocks

There needs to be a way to separate R code from your own writing. To process the R code, the processor has to know what part of the R Markdown document is code and what part is text. To separate, place R code in a code block.

R code blocks include the usual R code. The output of each code block, as with any R analysis, can include text as well as visualizations. Below are two code block examples in the sample document provided by RStudio.

Two R code blocks, one generates text, the other a visualization.

Code blocks can also be named, of particular use if there are coding errors in a long document. By naming the code block, the error diagnostics can list the name of the erroneous block, which pinpoints the source of the error. To name, list the chosen name of the code block after the r in the first line.

To create a code block, choose the Insert menu at the top of the window pane for the .Rmd file, and then choose the language, here R.

Generate new R code block.

Or, create a code bloc by manually entering the defining characters the code block.

Here is the new code block, ready for entered R code. Enter as many lines as you wish in any one code block, one or many lines.

The new R code block, ready for entry of R code.

Each code block can be displayed as part of your report, or not. Choose the “gear menu” located on the right side of each code block to select the desired option, or just enter directly.

Type of interaction with the output.

Optional Beginning Information

The beginning of an R Markdown document can optionally contain information about the document, such as the author’s name. The sample document from RStudio illustrates header information.

Rmd Document, Beginning.

Also optional is to reset the default display for this document. Here do not display this first R code chunk, but do display the code for all other code chunks in the output.

Override display defaults.

Generate the Report

Click the Knit button to generate the report that includes your writing as well as the output of embedded R code chunks within the document. The document is automatically saved when knit.

Knit the document, that is, generate the output, here an html file.

Get Help

Help is available. There is more to know, but the provided help page provides most or all of what you need to markup documents, such as headers, italics, images, etc. Choose the RStudio Help menu, then select Markdown Quick Reference.

Get R Markdown help.

Here is some of the help output, which appears in the lower-right window pane.

Example of help output.

Convert to Word

When finished with computer analysis and your writing, if desired, convert to MS Word output. Next to the Knit button is a little drop-down arrow. Click the arrow and choose your report type.

Choose Word document type for your report.

The result is a written report that combines your writing with data analysis output, in this example, output from R.